.TH std::allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::allocator \- std::allocator

.SH Synopsis
   Defined in header <memory>
   template< class T >        \fB(1)\fP
   struct allocator;
   template<>                 \fB(2)\fP (deprecated in C++17)
   struct allocator<void>;        (removed in C++20)

   The std::allocator class template is the default Allocator used by all standard
   library containers if no user-specified allocator is provided. The default allocator
   is stateless, that is, all instances of the given allocator are interchangeable,
   compare equal and can deallocate memory allocated by any other instance of the same
   allocator type.

   The explicit specialization for void lacks the member typedefs
   reference, const_reference, size_type and difference_type. This        \fI(until C++20)\fP
   specialization declares no member functions.

   The default allocator satisfies allocator completeness requirements. \fI(since C++17)\fP

.SH Member types

   Type                                                        Definition
   value_type                                                  T
   pointer (deprecated in C++17)(removed in C++20)             T*
   const_pointer (deprecated in C++17)(removed in C++20)       const T*
   reference (deprecated in C++17)(removed in C++20)           T&
   const_reference (deprecated in C++17)(removed in C++20)     const T&
   size_type                                                   std::size_t
   difference_type                                             std::ptrdiff_t
   propagate_on_container_move_assignment \fI(C++11)\fP              std::true_type
                                                               template< class U >

                                                               struct rebind
   rebind (deprecated in C++17)(removed in C++20)              {
                                                                   typedef allocator<U>
                                                               other;
                                                               };
   is_always_equal \fI(C++11)\fP(deprecated in C++23)(removed in     std::true_type
   C++26)

.SH Member functions

   constructor       creates a new allocator instance
                     \fI(public member function)\fP
   destructor        destructs an allocator instance
                     \fI(public member function)\fP
   address           obtains the address of an object, even if operator& is overloaded
   \fI(until C++20)\fP     \fI(public member function)\fP
   allocate          allocates uninitialized storage
                     \fI(public member function)\fP
   allocate_at_least allocates uninitialized storage at least as large as requested
   (C++23)           size
                     \fI(public member function)\fP
   deallocate        deallocates storage
                     \fI(public member function)\fP
   max_size          returns the largest supported allocation size
   \fI(until C++20)\fP     \fI(public member function)\fP
   construct         constructs an object in allocated storage
   \fI(until C++20)\fP     \fI(public member function)\fP
   destroy           destructs an object in allocated storage
   \fI(until C++20)\fP     \fI(public member function)\fP

.SH Non-member functions

   operator==         compares two allocator instances
   operator!=         \fI(public member function)\fP
   (removed in C++20)

.SH Notes

   The member template class rebind provides a way to obtain an allocator for a
   different type. For example, std::list<T, A> allocates nodes of some internal type
   Node<T>, using the allocator
   A::rebind<Node<T>>::other
   \fI(until C++11)\fP
   std::allocator_traits<A>::rebind_alloc<Node<T>>, which is implemented in terms of
   A::rebind<Node<T>>::other if A is an std::allocator
   \fI(since C++11)\fP.

   Member type is_always_equal is deprecated via LWG issue 3170, because it makes
   custom allocators derived from std::allocator treated as always equal by default.
   std::allocator_traits<std::allocator<T>>::is_always_equal is not deprecated and its
   member constant value is true for any T.

.SH Example


// Run this code

 #include <iostream>
 #include <memory>
 #include <string>

 int main()
 {
     // default allocator for ints
     std::allocator<int> alloc1;

     // demonstrating the few directly usable members
     static_assert(std::is_same_v<int, decltype(alloc1)::value_type>);
     int* p1 = alloc1.allocate(1); // space for one int
     alloc1.deallocate(p1, 1);     // and it is gone

     // Even those can be used through traits though, so no need
     using traits_t1 = std::allocator_traits<decltype(alloc1)>; // The matching trait
     p1 = traits_t1::allocate(alloc1, 1);
     traits_t1::construct(alloc1, p1, 7);  // construct the int
     std::cout << *p1 << '\\n';
     traits_t1::deallocate(alloc1, p1, 1); // deallocate space for one int

     // default allocator for strings
     std::allocator<std::string> alloc2;
     // matching traits
     using traits_t2 = std::allocator_traits<decltype(alloc2)>;

     // Rebinding the allocator using the trait for strings gets the same type
     traits_t2::rebind_alloc<std::string> alloc_ = alloc2;

     std::string* p2 = traits_t2::allocate(alloc2, 2); // space for 2 strings

     traits_t2::construct(alloc2, p2, "foo");
     traits_t2::construct(alloc2, p2 + 1, "bar");

     std::cout << p2[0] << ' ' << p2[1] << '\\n';

     traits_t2::destroy(alloc2, p2 + 1);
     traits_t2::destroy(alloc2, p2);
     traits_t2::deallocate(alloc2, p2, 2);
 }

.SH Output:

 7
 foo bar

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to   Behavior as published              Correct behavior
                       redundant comparison      propagate_on_container_move_assignment
   LWG 2103 C++11      between allocator might   provided
                       be required
   LWG 2108 C++11      there was no way to show  is_always_equal provided
                       allocator is stateless

.SH See also

   allocator_traits         provides information about allocator types
   \fI(C++11)\fP                  \fI(class template)\fP
   scoped_allocator_adaptor implements multi-level allocator for multi-level containers
   \fI(C++11)\fP                  \fI(class template)\fP
   uses_allocator           checks if the specified type supports uses-allocator
   \fI(C++11)\fP                  construction
                            \fI(class template)\fP
